<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>REST Services - Overview</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            margin: 0;
            padding: 2rem;
            background-color: #f9f9f9;
        }
        h1, h2 {
            color: #34495e;
        }
        ul {
            list-style-type: none;
            padding: 0;
        }
        li {
            margin: 0.5rem 0;
        }
        a {
            text-decoration: none;
            color: #2980b9;
            font-weight: bold;
        }
        a:hover {
            text-decoration: underline;
        }
        .note, .auth-note {
            background-color: #e7f3fe;
            border-left: 6px solid #2196F3;
            margin: 1rem 0;
            padding: 1rem;
        }
        code {
            background-color: #f4f4f4;
            padding: 0.2rem 0.4rem;
            font-size: 0.9rem;
        }
        pre {
            background-color: #f4f4f4;
            padding: 1rem;
            overflow-x: auto;
        }
    </style>
</head>
<body>
    <a href="../../../index.php">Home Page</a>
    <h1>REST Services Documentation</h1>
    <p>Welcome to the documentation for interacting with RESTful web services. This guide explains how to use various tools to make requests and includes a section on handling authentication if security is enabled.</p>

    <div class="note">
        <strong>Note for Beginners:</strong> If you are new to web services, each section includes basic examples using <code>curl</code> and <strong>Burp Suite</strong>. These examples will help you learn how to send requests and handle authentication when required.
    </div>

    <h2>Available Services</h2>
    <ul>
        <li>
            <a href="ws-echo.html">WS Echo Service</a> - A service to echo back messages sent to it, useful for testing connectivity.
        </li>
        <li>
            <a href="ws-dns-lookup.html">WS DNS Lookup Service</a> - Perform DNS lookups by providing a hostname.
        </li>
        <li>
            <a href="ws-test-connectivity.html">WS Test Connectivity Service</a> - Verify the connection to the web service.
        </li>
        <li>
            <a href="ws-user-account.html">WS User Account Service</a> - Manage user accounts with CRUD operations (Create, Read, Update, Delete).
        </li>
        <li>
            <a href="ws-login.html">WS Login Service</a> - Authenticate clients and receive a JWT for further requests.
        </li>
    </ul>

    <h2>Understanding Security Levels and Authentication</h2>
    <p>This system has multiple security levels that affect access to the web services:</p>
    <ul>
        <li><strong>Security Level 0</strong> - No authentication required. You can send requests without any additional headers or tokens.</li>
        <li><strong>Security Level 1 or Higher</strong> - Authentication with a JWT token is required for all services except <code>ws-login</code>. You must obtain a JWT token by logging in through the <code>ws-login</code> endpoint using your <code>client_id</code> and <code>client_secret</code>.</li>
    </ul>
    
    <div class="auth-note">
        <strong>Important:</strong> At security level 1 or higher, you must include a JWT token in the <code>Authorization</code> header for each request. Without a valid token, you will receive a <code>401 Unauthorized</code> error.
    </div>

    <h2>Step-by-Step Guide to Using JWT Authentication</h2>
    <ol>
        <li>
            <strong>Log In to Obtain a JWT Token:</strong>
            Send a POST request to the <a href="ws-login.html">WS Login Service</a> using your <code>client_id</code> and <code>client_secret</code> to authenticate. If successful, the response will include a JWT token.
            <p><strong>Example (curl):</strong></p>
            <pre><code>curl -X POST http://mutillidae.localhost/webservices/rest/ws-login.php \
-d "client_id=your-client-id&client_secret=your-client-secret"</code></pre>
            <p>The response will include a token in the format:</p>
            <pre><code>{"token": "your-jwt-token-here"}</code></pre>
        </li>
        
        <li>
            <strong>Save the Token:</strong> Copy the JWT token from the response and store it securely. You will need to include it in the Authorization header of each authenticated request.
        </li>
        
        <li>
            <strong>Include the Token in Requests:</strong> When calling any authenticated endpoint, include the token in the Authorization header using the format <code>Bearer &lt;your-token&gt;</code>.
        </li>

        <h3>Examples of Making Authenticated Requests</h3>
        <h4>Using curl</h4>
        <p>Below is an example of an authenticated request using <code>curl</code>:</p>
        <pre><code>curl -X GET http://mutillidae.localhost/webservices/rest/ws-dns-lookup.php?hostname=google.com \ 
-H "Authorization: Bearer &lt;your-token&gt;"</code></pre>

        <h4>Using Burp Suite</h4>
        <p>To send an authenticated request in Burp Suite:</p>
        <ol>
            <li>Open <strong>Burp Suite</strong> and navigate to the <strong>Repeater</strong> tab.</li>
            <li>Enter the URL in the Request line, such as:
                <pre><code>GET /webservices/rest/ws-dns-lookup.php?hostname=google.com HTTP/1.1
Host: mutillidae.localhost</code></pre>
            </li>
            <li>In the <strong>Headers</strong> section, add an Authorization header:
                <pre><code>Authorization: Bearer your-jwt-token-here</code></pre>
            </li>
            <li>Click <strong>Send</strong> to submit the request. If the token is valid, you will receive a successful response from the server.</li>
        </ol>
    </ol>

    <h2>How to Use the Services</h2>
    <p>Each service page provides:</p>
    <ul>
        <li>An overview of the service functionality.</li>
        <li>Examples of requests using Burp Repeater and <code>curl</code>.</li>
        <li>Details about the expected response from the service.</li>
        <li>Troubleshooting tips in case of issues.</li>
    </ul>

    <h2>Troubleshooting Common Issues</h2>
    <ul>
        <li>Ensure the web server is running and accessible on <code>mutillidae.localhost</code>.</li>
        <li>Verify the correct HTTP method (GET, POST, etc.) is used for each service.</li>
        <li>If using Burp Suite, confirm that traffic is correctly routed to the web service.</li>
        <li>If receiving a <code>401 Unauthorized</code> error, ensure your token is included in the <code>Authorization</code> header and has not expired.</li>
    </ul>

    <p>If you have any further questions or need assistance, feel free to reach out to your instructor or class support team.</p>
</body>
</html>
